<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
<title>Chordshop User Guide</title>
</head>
<body>
<center><h1>Chordshop User Guide</h1></center>
<hr/>
<h2><u>Introduction</u></h2>
<p>
The primary goal of Chordshop is to produce high quality PDF chord sheets and
chord sheet collections.  It uses the general ChordPro format and adds some extensions of its
own.  These extensions allow for advanced features like the support of
measures, on-the-fly transposition, and dual chord lines to show capoed chords
along with the actual chords.  It also provides a handy GUI for
editing ChordPro-like files and for exploring chord fingerings.
</p>
<hr/>
<h2><u>Why Use Chordshop?</u></h2>
<p>
There are plenty of programs that create chord sheets very well, but they
typically produce output with too little or too much information, or they
require too much effort to make a simple chord sheet.  The chord sheets that I
wanted to produce needed to have the usual chords over lyrics as well as timing
and performance information typically found in a leadsheet.
</p>
<p>
Chordshop provides this mix between a simple chord/lyric sheet and an actual
leadsheet.  The chords and lyrics can be printed in measures separated by
barlines. The barlines can also be "dotted" to indicate repeats, and repeat
brackets can be added to measures as well.  Sections of songs can be designated
as blocks for easy song navigation (e.g. chorus, bridge, verses).
</p>
<p>
The source files are simple text files in an extended ChordPro format.  Your
existing ChordPro files can be used as is.  (If you want to use Chordshop's
advanced features then you will need to add some notation to the files.)
Chordshop has a Song Editor built-in which can automatically convert plain text
chords into ChordPro format, add directives, transpose chords, and perform
other time-saving tasks.
</p>
<p>
Another major goal of Chordshop was to produce a tool that could be used with
any fretted instrument.  Most chord programs seem to be guitar-centric.
Chordshop produces chord diagrams for any instrument you care to define.  (Most
common instruments are already defined.)  The built-in Chord Explorer supports
any tuning with any number of strings.  It should help novice and expert alike
explore chord voicings for virtually any fretted instrument.
</p>
<hr/>
<h2><u>Requirements</u></h2>
<p>
These are minumum versions; later ones should work.
</p>
<ul>
<li>
<p>
Python 2.3
</p>
</li>
<li>
<p>
wxPython 2.5.1.5 (2.4 will not work!)
</p>
</li>
<li>
<p>
ReportLab 1.19
</p>
</li>
</ul>
<hr/>
<h2><u>Downloading</u></h2>
<p>
You can download Chordshop in two forms:
- Python Chordshop
  + This is the "source package", but it can also be run as is.
  + This can be run on any platform, but it requires certain packages to be preinstalled
    like Python, wxPython, and ReportLab.
  + This is packaged as a zip file.  Every platform has some version\variation of <tt>unzip</tt>,
    so this should not be a problem.  Also note that these files will use Windows line endings.
- Windows Chordshop
  + This is a standalone binary package that comes with all of the prerequisites included.
  + This is packaged as a self-extracting archive.  (It uses 7-zip for really good compression.)
  + If you want the source, download the Python Source package as well.
</p>
<hr/>
<h2><u>Chordshop Copyright and License Information</u></h2>
<p>
There is some more licence info in the licenses documentation <a href="licenses.html">here</a>.
At the very least, here is what you need to know about Chordshop:
</p>
<table border="1" bgcolor="#ffffee" width="80%" cellpadding="15">
<tr><td>
<p>
Copyright &copy; 2004 Blake T. Garretson
Email: blakeg@freeshell.org
</p>
<p>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.
</p>
<p>
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
</p>
<p>
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,
USA.
</p>
</td></tr></table>
<p>
If you downloaded the Windows binary package, some other packages were included.
You can read about their licenses (and find out how to get their source) in the
<a href="licenses.html">licenses documentation</a> as well.
</p>
<hr/>
<h2><u>Basic Concepts</u></h2>
<p>
Chordshop comes with its own philosophy, and it helps to understand this
approach before diving into using it.
</p>
<p>
I like plain text source files that are largely readable on their own.  I
should be able to edit them with any text editor I choose.  I should also be able to
feed these plain source files into the program from the command line to produce
great output with all the same features that the GUI has.  (If you are a Unix geek,
you can generate songbooks with nothing more that <tt>vi</tt> and a command-line.)  This allows for
batch processing and easy creation of song collections.  This is accomplished by separating
the code into two distinct programs: <tt>cs2pdf</tt> (the chord sheet generator) and <tt>chordshop</tt>
(the graphical frontend to <tt>cs2pdf</tt>.)  <tt>cs2pdf</tt> can be run as a standalone program, and does not
need the <tt>chordshop</tt> specific requirements installed to function (such as wxPython).  When
the name "Chordshop" is used in the documentation and elsewhere, it generallly refers to both
of these programs in a collective manner.  It is important to note that using the command-line
<tt>cs2pdf</tt> is never <em>necessary</em> since the <tt>chordshop</tt> frontend exposes all of the functionality
as well.
</p>
<p>
Another major concept is the separation of content and presentation.  The song source files
should only contain song specific information.  The display of the content should not be tied to
the source file.  This allow the user to utilize the same source file for multiple songbooks that
may use different fonts, instruments, transposition and capoing, etc.
</p>
<p>
This separation is achieved through Songbook files.  These are plain text files listing all of the
songs to be included in the collection, along with any configuration variables to be set for that
particular Songbook.
</p>
<p>
Here are a few other goals set at the beginning of this project:
- The PDF output should look outstanding.  It should look professional and it
  ought to look good enough to be found in a "real" chord book.
- The PDF output should be fully bookmarked and indexed for easy navigation in
  both printed and electronic form.
- The program should run on any platform that I might use, be it Linux, Unix,
  Windows, Mac, etc.
</p>
<hr/>
<h2><u>Configuration Scheme</u></h2>
<p>
Order of configuration precedence:
</p>
<ul>
<li>
<p>
<tt>cs2pdf.cfg</tt> file
</p>
<ul>
<li>
<p>
All of the available variables and default variables are in here.
</p>
</li>
<li>
<p>
Change anything you like, but never delete a variable.  That <strong>will</strong>
      break things.  You can comment out lines if you like with a "#".
</p>
</li>
</ul>
</li>
<li>
<p>
Songbook file variables
</p>
<ul>
<li>
<p>
See the Songbook File Format Guide
</p>
</li>
<li>
<p>
The are the lines that begin with "!"
</p>
</li>
</ul>
</li>
<li>
<p>
Chordpro Plus set directives
</p>
<ul>
<li>
<p>
See  the Chordshop File Format Guide
</p>
</li>
<li>
<p>
Example: {set:variable=value}
</p>
</li>
</ul>
</li>
<li>
<p>
Songbook file "pipe" overrides
</p>
<ul>
<li>
<p>
See the Songbook File Format Guide
</p>
</li>
<li>
<p>
After any given song title, variables can be changed for that
      specific song.
</p>
</li>
<li>
<p>
The pipe character is the delimiter.
</p>
</li>
</ul>
</li>
</ul>
<hr/>
<h2><u>Songbook Generation Configuration Variables</u></h2>
<p>
The complete list of configuration variables is in the <tt>cs2pdf.cfg</tt> file.
Here are descriptions of the most important.  All boolean varibles use 0 for "off"
or "false" and 1 for "on" or "true".
</p>
<h3><u>Transposition and Capoing</u></h3>
<p>
The <tt>transpose</tt> and <tt>capo</tt> variables can be combined, but <tt>transpose</tt> takes precedence. This means
that the song will <em>first</em> be transposed as indicated, and then capoed.
</p>
<dl>
<dt>
transpose
</dt>
<dd>
<p>
    This takes a comma separated list of (major) keys or intervals and adds the transposed
    versions to the output PDF. If intervals are used, both positive and negative
    numbers are accepted to transpose up or down.  If keys are used (e.g. C, G, Eb, F#),
    then the {key:} directive <em>must</em> be set as well so a starting point is established.<br/>
   <br/>
    If a comma separated list of values is given instead of a single value,
    the song is transposed and added to the PDF in the order that they are given.  The
    original key is not written the file unless specified with a zero value interval or
    the original key in the key list. The different versions of the song are
    labeled by their key, so adding the {key:} directive is highly recommended.<br/>
   <br/>
    The default value of <tt>transpose</tt> is 0, which indicates that nothing should be transposed.
</p>
</dd>
<dt>
capo
</dt>
<dd>
<p>
    If this is set, then two lines of chords will be printed: one line contains the chord shapes
    actually played, and the other shows the chords as they are heard when capoed at the given fret.
    The chords in the file are treated as the chords that will be <strong>played</strong> (not heard).
    If the key directive is included in the file, its value should be the key in which the
    chords are written.<br/>
   <br/>
    Like the <tt>transpose</tt> variable, multiple values can be given (e.g. capo=2,3,5)
    and the multiple versions will be put into the same PDF file.  The base
    key (the played key) will be the same in all of them, and the perceived
    chords change.<br/>
   <br/>
    A key directive is not required with <tt>capo</tt>, but it is strongly encouraged.
    If it is not given, the PDF outline titles are
    rather generic like "Song Title (Subtitle) -&gt; Capo 2" instead of a more informative
    "Song Title (Subtitle) -&gt; in C, Capo 2 into D".<br/>
   <br/>
    The default <tt>capo</tt> value is 0. For a capo list, one of the items can be a zero,
    and that version of the song is printed without the double
    chord lines.  It will look like there is no capo directive for that one item, but the
    rest will work as expected.
</p>
</dd>
</dl>
<h3><u>Miscellaneous</u></h3>
<dl>
<dt>
index
</dt>
<dd>
<p>
    This determines style of index to use (or not use).
    It can take these values:
</p>
<ul>
<li>
<p>
0 = do not create index
</p>
</li>
<li>
<p>
1 = create alphabetized index
</p>
</li>
<li>
<p>
2 = create alphabetized index if there is more than one song
</p>
</li>
<li>
<p>
3 = create unalphabetized index
</p>
</li>
<li>
<p>
4 = create unalphabetized index if there is more than one song
</p>
</li>
</ul>
</dd>
<dt>
chordpro_mode
</dt>
<dd>
<p>
    Forces ChordPro Plus files to be printed without measures and bars,
    i.e. just like normal ChordPro files.  The bars are extracted from the file if they are there,
    but then ignored during writing.
</p>
</dd>
<dt>
instrument
</dt>
<dd>
<p>
    Set this to a chord definition file name to choose the instrument.
</p>
</dd>
</dl>
<h3><u>Fonts</u></h3>
<p>
The fonts used in the generated PDF files are all listed in the <tt>cs2pdf</tt> configuration file.
Acrobat Reader comes with 14 fonts built in, and these are the fonts that Chordshop supports.
Any other fonts used in PDF's would need to be embedded, and that complicates matters and increases
the PDF filesize.  By using the internal fonts, Chordshop generated PDF files are usually very small.
A 1KB ChordPro Plus file will often produce a 5 KB PDF.
</p>
<p>
The 14 fonts available for use are:
- Courier
- Courier-Bold
- Courier-BoldOblique
- Courier-Oblique
- Helvetica
- Helvetica-Bold
- Helvetica-BoldOblique
- Helvetica-Oblique
- Symbol
- Times-Bold
- Times-BoldItalic
- Times-Italic
- Times-Roman
- ZapfDingbats
</p>
<p>
Cleary, there isn't much reason to use Symbol or ZapfDingbats, so that leaves you with
a respectable collection of three font families: a serif, sans serif, and monospaced font; each in
regular, bold, italic (Oblique), and bold plus italic (BoldOblique).  The choices aren't overwhelming,
but they cover all of the major categories that anyone should need.  I will probably never add support
for any additional fonts.
</p>
<p></p>
<p></p>
<hr/><p><small>
Copyright 2004, Blake T. Garretson, All rights reserved.<br />
Last updated 07-Jul-2004 22:07:03 Eastern Standard Time
</small></p>
</body>
</html>
